Aminet 1

home *** CD-ROM | disk | FTP | other *** search

/ Aminet 1 / Aminet - June 1993 [Walnut Creek].iso / usenet / sources / volume90 / libraris / reqlib12 / part03 < prev

Wrap

Internet Message Format | 1990-09-28 | 62.7 KB

Path: abcfd20.larc.nasa.gov!amiga-request From: amiga-request@abcfd20.larc.nasa.gov (Amiga Sources/Binaries Moderator) Subject: v90i261: requester.library 1.2 - requester library, Part03/03 Reply-To: Paul-Erik Raue <peraue@cs.vu.nl> Newsgroups: comp.sources.amiga Message-ID: <comp.sources.amiga:v90i261@abcfd20.larc.nasa.gov> References: <comp.sources.amiga:v90i259@abcfd20.larc.nasa.gov> Date: 28 Sep 90 18:45:55 GMT Approved: tadguy@uunet.UU.NET (Tad Guy) X-Mail-Submissions-To: amiga@uunet.uu.net X-Post-Discussions-To: comp.sys.amiga Submitted-by: Paul-Erik Raue <peraue@cs.vu.nl> Posting-number: Volume 90, Issue 261 Archive-name: libraries/reqlib-1.2/part03 #!/bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh <file", e.g.. If this archive is complete, you # will see the following message at the end: # "End of archive 3 (of 3)." # Contents: req.doc # Wrapped by tadguy@abcfd20 on Fri Sep 28 14:45:31 1990 PATH=/bin:/usr/bin:/usr/ucb ; export PATH if test -f 'req.doc' -a "${1}" != "-c" ; then echo shar: Will not clobber existing file \"'req.doc'\" else echo shar: Extracting \"'req.doc'\" $60498 characters$ sed "s/^X//" >'req.doc' <<'END_OF_FILE' X X The req.library is a run time re-entrant library that is designed Xto make it easier for programmers to use powerful, easy to use Xrequesters for communicating with users. The requester library Xincludes such functions as a color requester, file requester, message Xdisplay requester and many functions to make the creation of gadgets Xfor your own custom requesters easier. X X Req.library was written by Colin Fox (of Pyramyd Designs) and XBruce Dawson (of CygnusSoft Software). Req.library is a freely Xdistributable library that may be used in commercial products without Xpaying any royalties. We encourage you to use the requester library Xin all of your programs, to make them easier to write, and to use. X X Req.library is not public domain. The requester library and all Xdocumentation and example programs are all copyright 1989. X X The requester library must be distributed with the documentation Xfile (req.doc), and the three include files (req.h, reqbase.h and Xreqbase.i). X X X X Req.library is dedicated to the programmers who make the Amiga Xshine the way it was meant to. X X XOverView: X X All of the req.library functions that bring up requesters allow Xyou two ways of specifying what screen you would like the requester to Xappear on. The first way is the more efficient way, because you only Xhave to set it up once and then it takes care of things automatially. XThere is a field in all process structures called the pr_WindowPtr. XThis pointer is used by DOS to decide where to put it's requesters. XIf pr_WindowPtr contains a zero, requesters go on the workbench Xscreen. If it contains the address of a window, then requesters go on Xthat window's screen. If it contains a negative one, then no DOS Xrequesters come up. The req.library requesters all use this variable, Xif they are called from a process . However, if the pointer is -1, Xthe req.library functions do still appear, on the workbench screen. X X The second way was put in mainly so that the requesters can be Xcalled from tasks. Since a task does not have a process structure, it Xalso lacks a pr_WindowPtr. Therefore, all of the requester functions Xwhich can be used from a task (currently everything except the file Xrequester) can be passed a window pointer, either as a parameter or as Xan element in a structure. Important: This pointer takes precedence Xover the pr_WindowPtr so if you wish the requesters to use the Xpr_WindowPtr you must zero the window fields that the routines are Xexpecting. In the case of fields in a structure this can be easy as Xlong as you make sure your structure defaults to being zero Xeverywhere. X X Setting the pr_WindowPtr is quite a simple matter. All you have Xto do is do a FindTask((char *)0); which returns a pointer to your own Xtask and your own process (a task structure is the first element of a Xprocess structure). Then you simply preserve the old value of Xpr_WindowPtr (VERY IMPORTANT!!!) and put a window pointer into it. X Xeg: X /* Find my task. */ X myprocess = (struct Process *)FindTask((char *)0); X oldwindowptr = myprocess->pr_WindowPtr; X myprocess->pr_WindowPtr = window; X Xor: X X MOVE.L 4,A6 X MOVE.L #0,A1 X SYS FindTask ;Find my task. X MOVE.L D0,_myprocess X MOVE.L D0,A0 X MOVE.L pr_WindowPtr(A0),_oldwindowptr X MOVE.L _window,pr_WindowPtr(A0) X X Before your program exits it is VERY important that it restore the Xprevious value of pr_WindowPtr. If you don't, then your program will Xwork in some situations, but will BLOW UP in others. For example, if Xyou execute (without using the 'run' command) a program, which then Xsets the pr_WindowPtr to point at one of its windows and the exits Xwithout restoring it, then the next time a DOS requester tries to Xappear... BOOM! The machine will probably crash as DOS tries to open Xa requester on a now closed screen. Therefore, before leaving: X X myprocess->pr_WindowPtr = oldwindowptr; X Xor: X X MOVE.L _myprocess,A0 X MOVE.L _oldwindowptr,pr_WindowPtr(A0) X X X X One final note. The pr_WindowPtr field exists in the process Xstructure. This means that a task does not have this field. XTherefore, if you want to call one of the requester library functions Xfrom a task, you will not be able to specify what screen you would Xlike the requester to appear on by setting the pr_WindowPtr field. XAll of the functions that open requesters and can be called from a Xtask (the file requester/font requester is the only one that can't be Xcalled froma task) have some other way of specifying which screen you Xwould like them to open on. They will have either have a field in the Xstructure which you must pass them or a parameter which can contain a Xwindow pointer to one of the windows on your custom screen. If this Xpointer is non-zero then it overrides the pr_WindowPtr field. X X X X X By opening the requester library, you not only gain access to all Xof the functions documented below, but to some other goodies as well. XReq.library needs and therefore opens several other libraries, Xincluding dos.library, intuition.library, graphics.library and the Xconsole device. All of these pointers are stored in the ReqLib Xstructure which you get a pointer to when you open the req.library. XTherefore, you can save yourself a little bit of code by grabbing Xthese fields after opening the requester library. The only thing to Xbeware of is don't use these values after you have close the requester Xlibrary, because at that point there is no guarantee that they will Xstill be valid. X X In addition to these libraries, the Images pointer in the req Xlibrary structure points to a set of ten small images (four arrows and Xssix letters) which have are guaranteed to be in chip memory. These Xcan be used if your program requires this type of images. X X X X X One thing to keep in mind when using the gadget creation routines Xis that there isn't any way for us to check that you have passed us a Xpointer to the correct size of buffer, so you _must_ make sure that Xyou are allocating the right amount of memory. X X X-------------------------------------------------------------- XHere's a quick list of the functions available: X-------------------------------------------------------------- X XCenter..................Center a new window over the mouse. X XSetSize.................Prop gadget handling routines (32 bit) XSetLocation XReadLocation X XFormat..................sprintf() format routine X XSimpleRequest...........Starter gluecode to TextRequest- Single gadget XTwoGadRequest...........Starter gluecode to TextRequest- Two gadgets X XFileRequester...........FileRequester routines XPurgeFiles X XColorRequester..........a colorrequester X XMakeGadget..............Gadget creation routines XMakeString XMakeProp XMakeButton X XMakeScrollBar...........3 part gadget; 2 arrows and a prop. X Horizontal or Vertical X XLinkGadget..............Gadget creation routines that self-hook into X the newwindow XLinkStringGadget........gadget list. XLinkPropGadget X XDrawBox.................Draw a box (x1y1)(x2y2) in one command X XGetFontHeightAndWidth...return height and width of current font X XRealTimeScroll..........scroll routine used in file requester X XTextRequest.............Powerful requester function X XGetString...............Get a line of text from the user XGetLong.................Get a signed long from the user X XRawKeyToAscii...........Convert raw key to ascii X X---------------------------------------------------------------- X X XNAME X Center X X XSYNOPSIS X Center( &nw, x, y) X A0 D0 D1 X Xstruct NewWindow *nw; XUSHORT x,y; X XDESCRIPTION X X Center() is used to adjust a NewWindow structure so that the Xwindow that it opens will appear immediately under the mouse. The x,y Xvalues are used to specify which part of the window you would like to Xappear underneath the mouse. If x or y is zero, that tells Center() Xto position the window so that the window center (in the x or y Xdirection respectively) is underneath the mouse. If x or y is Xpositive, that tells Center() to position the window so that the mouse Xis that many pixels from the left or top edge of the window Xrespectively. If x or y is negative, that tells Center() to position Xthe window structure so that the mouse appears that many pixels from Xthe right or bottom edge of the window respectively (ie; x = -10 tells XCenter to position the mouse ten pixels to the left of the right Xedge). X X If it is impossible to position the window exactly where requested X(if the mouse pointer is too close to the edge of the screen) then Xthis routine will position the window as close as possible to the Xcorrect location. X X To allow this routine to work accurately it is necessary to have Xalready initialized the new window structure to specify on what screen Xthe window is going to be open. ie; you should set the Type and XScreen fields before calling Center(). X X This routine disturbs no registers. X XRETURNS X nothing XSEE X XBUGS X None known X X X;-------------------------------------------------------------------- X XNAME X SetSize XSYNOPSIS X X SizeVal=SetSize(MaxValue,ViewSize) X D0.W D0.L D1.L X Xshort SizeVal; Xlong MaxValue,ViewSize; X XDESCRIPTION X X This routine is designed to correctly handle sizing a prop gadget Xto a range. The range is given in in MaxValue/ViewSize. MaxValue is Xthe maximum value that this prop is supposed to be able to represent. XViewsize is how large the display area is. For instance, if your Xmaximum value was 200 (files, for example), and your viewsize was 15 X(lines of text), then you would call this as so: X X SizeVal=SetSize(200,15); X X Then you would put SizeVal into the appropriate PropInfo structure Xelement (in the case of the file requester, that would be VertBody). X XRETURNS X The 16 bit value to be put into the PropInfo structure of the Xprop gadget. X XSEE X SetLocation, ReadLocation XBUGS X Bugs? what bugs? X X X;-------------------------------------------------------------------- X XNAME X SetLocation XSYNOPSIS X XNewLoc = SetLocation(MaxValue,ViewSize,Value); X D0 D0 D1 D2 X Xshort NewLoc; Xlong MaxValue,ViewSize,Value; X XDESCRIPTION X X When you have a prop gadget that you wish to directly set, Xthen this is the routine to use. It allows you to pass any 32 bit Xvalue and properly set the gadget. X XRETURNS X X The return is the value to put into either HorizPot or VertPot, Xdepending on what orientation you have the gadget. X X XBUGS X X n/a X XEXAMPLE X XSEE X SetSize(),ReadLocation() X X;-------------------------------------------------------------------- X XNAME X ReadLocation XSYNOPSIS X XLocVal=ReadLocation(MaxValue,ViewSize,PotValue) X D0 D0.L D1.L D2.W X Xlong LocVal,MaxVal,ViewSize; Xshort PotValue; X X XDESCRIPTION X X If you prop gadget has been moved, this is the routine that Xyou would use to determine where it's been moved to. X XRETURNS X Returns the decoded value of the prop, as an unsigned 32 bit. XThis is the element number (line number usually) that should be Xdisplayed on the first line of your display window. X XSEE X X SetSize(), SetLocation() X XBUGS X n/a X XEXAMPLE X X;-------------------------------------------------------------------- X XNAME X Format XSYNOPSIS X X Format(Buffer,string,values) X A2 A0 A1 X Xchar *Buffer,string[]; Xchar **values; X XDESCRIPTION X X This does the same thing as sprintf(), except that it isn't in Xthe stdio library, and doesn't use up very much room. This function Xuses the ROM function RawDoFmt to do the print() style formatting. XThis routine does not allow the use of all of the '%' directives (for Xexample, floating point numbers can not be printed with this). For Xfull documentation on what directives are supported, see the Xdocumentation on RawDoFmt. This is the routine that TextRequest (and Xtherefore SimpleRequest and TwoGadRequest) use for their text Xformatting, so these restrictions apply to them also. X X The RawDoFmt routine also assumes that 'int's are sixteen bits Xlong. Therefore, if you are using a compiler with an int size of Xthirty-two bits and you want to print an int or a short, you must use X'%ld', rather than '%d'. X XRETURNS X The number of characters in the formatted string. XBUGS X none known X XEXAMPLE X X Format(Buffer,"There are %d changes to the file %s.",numchanges, Xfilename); X X Format(Buffer,"%x is a hex number, %c is a character.", num, chr); X XSEE X TextRequest, SimpleRequest, TwoGadRequest. X Further information on printf() style formatting is available in Xthe AutoDocs on RawDoFmt and in C manuals discussing printf(). X X;-------------------------------------------------------------------- X X X XNAME X ColorRequester XSYNOPSIS X XNewColor=ColorRequester(DesiredColor); X D0 D0 Xlong DesiredColor; X XDESCRIPTION X X This is a full-fledged color requester. It is intelligent enough Xto open with the right number of colours in the palette automatically. XIt shows you both the colour you are working with, and the numerical XRGB value of that colour. It has Spread, Undo, Ok and Cancel Xfunctions. Planned is the addition of HSV. X X The cursor keys move the color-cursor around the palette, RETURN Xselects the current color and ESC cancels out. X X You pass this routine the color that you would like initially Xhighlighted (typically the current drawing colour). X X The ExtendedColorRequester function has slightly more options, but Xis slightly more work to call. X XRETURNS X X Color number that the user selected, -1 if the user cancels the Xcolour requester. The changed colours will be in the viewport Xstructure for your screen. X XSEE X ExtendedColorRequester X XBUGS X X none known. X XEXAMPLE X X newcolor = ColorRequester(oldcolor); X X;-------------------------------------------------------------------- X XNAME X ExtendedColorRequester XSYNOPSIS X XNewColor=ExtendedColorRequester(&(struct ExtendedColorRequester) X D0 A0 Xstruct ExtendedColorRequester colorreqstruct; X XDESCRIPTION X This call brings up exactly the same color requester as the XColorRequester call. The only difference is that this routine allows Xyou to specify more parameters. The difference is actually quite Xsmall right now, because there is only one additional parameter that Xcan be passed through this entry point. This is the ecr_window Xparameter, used to specify what window (and hence what screen) the Xcolor 'requester' appears on. This parameter is rarely needed because Xthe window the requester opens up on can be specified by setting the Xpr_WindowPtr field in your process structure to the address of your Xwindow structure (see the beginning of the docs for an overview on Xthis procedure). The only time this entry point is needed, currently, Xis if you try to bring up the color requester on a custom screen from Xa task, since a task does not have a pr_WindowPtr and can therefore Xnot specify the window and screen. X XRETURNS X X Color number that the user selected, -1 if the user cancels the Xcolour requester. The changed colours will be in the viewport Xstructure for your screen. X XSEE X ColorRequester X XBUGS X X none known. X XEXAMPLE X X /* This should generally be declared as a global variable */ X /* so that all of it's elements get initialized to zero. */ X /* If you declare it as a local variable, be sure to zero */ X /* all of the fields, even the unused ones. */ X struct ExtendedColorRequester colorstruct; X X colorstruct.defcolor = 0; X colorstruct.window = mywindow; X newcolor = ExtendedColorRequester(&colorstruct); X X;-------------------------------------------------------------------- X XNAME X MakeGadget XSYNOPSIS XMakeGadget(Buffer,String, X, Y) X A0 A1 D0 D1 Xstruct Buffer *GadgetBlock; Xchar *String; Xlong D0,D1; XDESCRIPTION X X This routine prepares a buffer to be a standard BOOLEAN text Xgadget. This is a simple way of producing gadgets for code that must Xbe reentrant, and it is more efficient than defining gadgets in data Xstatements. The routine initializes the gadgets to a set of X'standard' values that should cover most cases and then links the four Xparts of the GadgetBlock together. X X Buffer is a pointer to a unitialized GadgetBlock, which contains Xthe necessary Gadget, Border, border pairs and IntuitText structures Xneeded to render a boolean gadget with a border and some text. X X String is a pointer to the text that should appear inside the Xgadget. The gadget is automatically sized to match the strings Xlength. X X X and Y are the gadgets initial position, they are simply copied Xinto LeftEdge and TopEdge in the gadget structure. X XRETURNS XSEE XBUGS XEXAMPLE X X X;-------------------------------------------------------------------- X XNAME X MakeString X XSYNOPSIS XMakeString(Buffer,StringBuff,UndoBuff,MaxWidthBits,MaxNumChars, X, Y) X A0 A1 A2 D0 D1 D2 D3 X Xstruct Buffer *StringBlock; Xchar *StringBuff; Xchar *UndoBuff; Xlong MaxWidthBits, MaxNumChars, X, Y; X XDESCRIPTION X X As with all of the MakeGadget functions, this one prepares a Xbuffer to be used as a string gadget, that may be used re-entrantly. XThe buffer need not be cleared first. This means that you may create Xa temporary gadget on the stack. X X The StringBuff is where the body of text inside the gadget will Xreside. X X When the gadget is activated, the text in StringBuff is Xautomatically copied (by intuition) into UndoBuff. This allows you to Xtype Amiga-Q and get the old string back. This field may be null if Xyou wish to have no undo. X X MaxWidthBits is the width of the frame around the gadget. X X MaxNumChars is the maximum number of characters that you will be Xable to type into the gadget, including the terminating zero on the Xstring. MAKE SURE that this number is no greater than your StringBuff Xsize, or else you're going to be typing over memory that isn't yours. X X X,Y are the position of the upper left hand corner of the gadget. XThe border is actually 2 pixels above and to the left of this corner. X XRETURNS X Nothing XSEE X X MakeGadget,MakeProp,MakeScrollbar,LinkGadget,LinkProp,LinkString X X X;-------------------------------------------------------------------- X XNAME X MakeProp XSYNOPSIS X XMakeProp(Buffer,Width,Height,Flags) X A0 D0 D1 D2 X Xstruct Buffer *PropBlock; Xlong Width, Height, Flags; X XDESCRIPTION X X This routine prepares an un-initialized buffer for use as a prop Xgadget. X X Buffer, on return, will contain the gadget, along with the Xnecessary PropInfo and Image structures, all linked together. X X Width is the with of the container, in pixels. X Height is the height of the container in pixels. X X The Flags parameter is where you decide if you want FREEHORIZ, XFREEVERT, or both. It is simply copied into the gadget flags field. X X XRETURNS X X Nothing X X X;-------------------------------------------------------------------- X XNAME X DrawBox XSYNOPSIS X XDrawBox(rp,MinX,MinY,MaxX,MaxY) X A1 D0 D1 D2 D3 X Xstruct RastPort *rp; Xlong MinX,MinY,MaxX,MaxY; X X XDESCRIPTION X X This routine allows you to draw a simple box in one command. XIt draws the box in APen color, in the current draw mode, with the Xcurrent line pattern. X X (MinX,MinY) are the upper left corner of the box, and X(MaxX,MaxY) are the lower right. X X The pen is left at the upper left corner (MinX,MinY). X X;-------------------------------------------------------------------- X XNAME X MakeButton XSYNOPSIS X XMakeButton(Buffer,Image,Image2,Width,Height,Depth) X A0 A1 A2 D0 D1 D2 X X Xstruct TwoImageGadget *Buffer; Xchar *Image; /* Pointer to the actual bitplane data */ Xchar *Image2; /* Pointer to the second image. */ Xlong Width,Height,Depth; X X X X XDESCRIPTION X X The purpose of this routine is one similar to MakeGadget, but Xinstead of using text for the button, it uses a graphic. You supply a Xbitmap, and MakeButton will use it in it's rendering. X X You may have either one or two images, the routine handles it Xroutinely. If you supply one image, then this sets GADGHCOMP, and if Xyou have two images, it sets GADGHIMAGE. RELVERIFY is always set, so Xas long as you the user is pressing that gadget, the alternate Xhighlight is shown. X X Buffer has room for two images. X X Image is a pointer to the actual image data, in CHIP memory, for Xthis gadget. X Image2 is a pointer to the alternate image data. X X Width and Height make up the size of your image. X X Depth is how many bitplanes of data you've supplied. X XBUGS X It's not really a bug, but if your images aren't the same size, Xthen one won't erase the other when it is drawn, so you may be showing Xan image with traces of the other one left there. X X;-------------------------------------------------------------------- X XNAME X MakeScrollBar XSYNOPSIS X XMakeScrollBar(Buffer,Flags,Size,X,Y) X A0 D0 D1 D2 D3 X Xstruct ScrollBlock *Buffer; Xlong Flags,Size,X,Y; X X XDESCRIPTION X X This is a special routine that creates a scrollbar (which consists Xof a prop gadget and two arrows) and you handle it like it's a single Xgadget. You may have either a horizontal scrollbar, or a vertical Xscrollbar. These scrollbars are very much like the ones in workbench Xwindow borders. These use slightly different images on the arrows, Xhowever. X X The way you determine how this set up and oriented is by flag Xcombinations. If you wished to put a scrollbar in the bottom border Xof a window, then you would pass (in flags): X X Flags = (HORIZSLIDER | GRELBOTTOM | GRELWIDTH) X X If you wished it in the right border: X X Flags = (VERTSLIDER | GRELRIGHT | GRELHEIGHT) X X The idea is to allow you to manipulate the scrollbar as though it Xwere a single gadget, not three. If you pass confusing flags (like XGRELBOTTOM|GRELHEIGHT) then it is undefined what will happen. X X If all you want is a simple scrollbar that doesn't size, then just Xset VERTSLIDER or HORIZSLIDER. X XSEE X X X;-------------------------------------------------------------------- X XNAME X PurgeFiles XSYNOPSIS X PurgeFiles(&FileRequesterStructure) X A0 XDESCRIPTION X Clear up all memory and file locks allocated by the file Xrequester. This routine must be called before your program exits if Xyou use the file requester with either FRQEXTSELECTM bit set or the XFRQCACHINGM bit set. The first bit is if you want the user to be able Xto select multiple files. The file requester has to allocate a linked Xlist of file names which this function will purge. The FRQCACHINGM Xbit is set if you want the file requester to remember the contents of Xa directory between calls. X X This routine can be called any time you want the buffers and file Xlocks purge. X XRETURNS X This routine does not return anything. X XSEE X FileRequest XBUGS X None known. XEXAMPLE X Xmain() X { X FileRequest(&FileRequesterStructure); X X . X . X . X X PurgeFiles(&FileRequesterStructure); X } X X X X;-------------------------------------------------------------------- X XNAME X GetFontHeightAndWidth XSYNOPSIS X XDESCRIPTION X X This allows you quick access to the font attributes set by the Xuser in preferences. The font width is returned in D0 and the height Xis returned in D1. X XRETURNS XSEE XBUGS XEXAMPLE X X X X;-------------------------------------------------------------------- X XNAME X LinkGadget XSYNOPSIS X XLinkGadget(Buffer,String,nw, X, Y) X A0 A1 A3 D0 D1 X Xstruct GadgetBlock *Buffer; Xchar *String; Xstruct NewWindow *nw; Xlong X,Y; X XDESCRIPTION X X This is actually a superset of the previous command MakeGadget. XWhat this does is automatically link the gadget into your NewWindow Xstructure's gadget list. X X No registers are disturbed. X XSEE X MakeGadget XBUGS X n/a X X X X;-------------------------------------------------------------------- X XNAME X LinkStringGadget XSYNOPSIS XLinkStringGadget(Buffer,StringBuf,UndoBuf,nw, WidthBits,NumChars, X, Y) X A0 A1 A2 A3 D0 D1 D2 D3 X Xstruct StringBlock *Buffer; Xchar *StringBuf; Xchar *UndoBuf; Xstruct NewWindow *nw; Xlong WidthBits,NumChars,X,Y; X XDESCRIPTION X X This is number 2 in the LinkGadget routines. This one obviously Xlinks the string gadget to the window's gadget list. In fact, the Xonly difference between this and the MakeString routine is the Xaddition of the NewWindow pointer. X XSEE X MakeStringGadget X X X;-------------------------------------------------------------------- X XNAME X LinkPropGadget XSYNOPSIS X XLinkPropGadget(Buffer,nw, Width, Height, Flags, LeftEdge, TopEdge) X A0 A3 D0 D1 D2 D3 D4 X Xstruct PropBlock *Buffer; Xstruct NewWindow *nw Xlong Width,Height,Flags,LeftEdge,TopEdge; X XDESCRIPTION X X Here we have a superset for MakeProp. It works exactly the same Xas MakeProp, except that it attaches the gadget to the head of the Xlist in the window. X XSEE X MakeProp X X X;-------------------------------------------------------------------- X XFileRequester X XNAME X FileRequester - bring up a file/font requester. X XSYNOPSIS X success = FileRequester(&FileRequesterStructure) X D0 A0 X XFUNCTION X Bring up a fully intuitionized file/font requester (actually a Xwindow) and let the user select a file/font. X XINPUTS X &FileRequesterStructure - pointer to an initialized (can be Xinitialized mostly to zeroes) file requester structure. X XRESULT X Returns TRUE or FALSE to say whether the user selected a file or Xnot. The file name(s) or font selected are then found by looking at Xthe file requester structure whose address was passed. X X For ideas on customizing the file requester for your particular Xsystem (thus overriding the defaults used by programmers who use the Xfile requester) see the customizefile.asm file. X XBUGS X Problem with an Intuition bug that messes up the current active Xwindow if a window closes when one of its string gadgets is still Xactive. This bug show up if you run the file requester straight from Xa CLI window and then exit it with Amiga-L. X I have heard that it resets some window flags when run on a custom Xscreen, but I believe this is a feature of Intuition, not of the file Xrequester. X XSEE ALSO X PurgeFiles X X X The file requester in the requester library allows to put a Xpowerful and easy to use file requester into your programs with a Xminimum of work and at a very small expense in program size. The file Xrequester was designed to be as easy as possible to call, while not Xsacrificing power. X X To get the file requester to come up all you need to do (after Xopening the requester library of course) is to allocate space for a XFileRequester structure and then call the file requester with the Xaddress of this structure, with all fields initialized to zero, like Xthis: X Xstruct FileRequester MyFileReqStruct; X Xsuccess = FileRequester(&MyFileReqStruct); X X The function will return either one or zero for success or failure Xrespectively. X X You can specify what screen the file requester should appear on in Xone of two ways. If you want it to appear on a custom screen, then Xthe best way is to set the pr_WindowPtr field in your process Xstructure to point at one of the windows on your screen (this should Xbe done anyway, so that DOS requesters appear on your custom screen). XThis field is looked at by all functions in the requester library so Xthis way is the simplest method. The other way, which overrides the Xpr_WindowPtr field is to initialize the frq_Window field to point at Xone of your windows. If this field is non-zero, it is used instead of Xthe pr_WindowPtr field of your process structure. Important note: It Xis VERY important that you reset the pr_WindowPtr field back to its Xoriginal value before your program exits. If you don't, the next Xprogram run may try to open a requester window on a now closed screen. X X The file requester was carefully designed so that it could be Xcalled without having to initialize very many fields. This is Xdemonstrated by seeing that it is possible to call it without Xinitializing any fields. There are a few fields that are necessary to Xactually get any use out of it, but very view. Those few are Xdocumented in the following paragraph. X X Although you can bring the file requester up without initializing Xany fields there are a couple of fields that you will definitely want Xto initialize. The file requester isn't much use unless you get a Xfile name back out of it, and for this you need to initialize the Dir Xand File fields. These two fields should point to character arrays Xthat are, respectively, DSIZE+1 and FCHARS+1 bytes long. When the Xfile requester is first run the file requester looks in these arrays Xfor the default directory and file names and if the user selects a Xfile name the directory and file name are copied back into these Xarrays. You will probably want to initialize the Title field with the Xmessage that you want to have appear at the top of the file requester Xwindow. X X If you initialize the PathName field (it should point an array of Xat least DSIZE+FCHARS+2 characters) then when the user selects a file, Xthe complete path name will be put into this array. X X The Window field is used to specify what window the file requester Xis associated with. This is used to get the file requester to show up Xon a custom screen. Generally this field should be unnecessary. XThere is a variable provided in a process structure which is used for Xthis purpose. Any program that opens a custom screen and uses any DOS Xfunctions should set the pr_Window pointer in their process structure Xto a pointer to their window so that DOS requesters will show up on Xtheir custom screen. If you do this, then the file requester will Xalso show up on your custom screen. If you are not using a custom Xscreen then you don't need to set the pr_Window pointer or the Window Xfield in the file requester structure. Note: If you do set the Xpr_Window structure in the process structure, be sure to return it to Xits old value before your program exits. X X If the extended select bit is set in the Flags field then the XMaxExtendedSelect fields specifies the maximum number of files that Xthe user can select. This is ignored if the extended bit isn't set in Xthe Flags field. X X numlines and numcolumns specify the maximum size that the file box Xwill be in characters. If the system is low on memory, or the screen Xis too small, these will be shrunk as necessary. devcolumns is the Xnumber of columns of characters wide that the device box will be. X X The Flags field can currently contain seven different flags. The Xfirst flag, FRQSHOWINFOM, specifies whether or not '*.info' files X(files containing information for icons) should be filtered out. The Xdefault is for them to be filtered. X X The FRQEXTSELECTM flags specifies whether extended select is Xwanted. If you set this flag then you should probably also set the XMaxExtendedSelect field. If you don't then the maximum number of Xfiles the user will be able to select will be 65536, which is a bit Xhigh for most purposes. Note: If you use this bit then you _must_ Xcall PurgeFiles() with the address of your FileRequester structure Xafter the last time you call the file requester, in order to free up Xany memory used in the extended select structures. When the user Xselects multiple files, a linked list of the file names selected (not Xincluding the directory name) will appear in the ExtendedSelect field. XThe list is a linked list of ESStructures. The directory name which Xshould be prepended to all of these names will appear in the array Xpointed to by the Dir field. X X The FRQCACHINGM flag specifies whether or not directories are Xcached from one call to the next. This is a very handy features, Xespecially for those who lack hard drives. However, if this features Xis used, you _must_ call the PurgeFiles() routine with the address of Xyour FileRequester structure after the last time you call the file Xrequester, in order to free up any memory used in caching. X X As well as being a file requester, this routine can be used as a Xfont requester too. Just set the FRQGETFONTSM flags to turn it into a Xfont requester. You should also put the name 'fonts:' in the Dir Xarray. The file/font requester will return a one or zero for success Xor failure as usual, the font name will be returned in the File array Xand the font size and style will be returned in the FontYSize and XFontStyle fields. Note that the font requester allows the user to Xchange the directory where the fonts are read from. Although you Xshould put 'fonts:' there, you should allow for the possibility that Xthe user might change the directory. They might, perhaps, have a Xseparate disk full of fonts. The simplest way to deal with fonts Xcoming from different directories, is to set the PathName field Xinstead of the Dir field. You can then use the string in the PathName Xfield (which will contain the directory and font name) as the font Xname. If you don't do this, then you have to concatenate the font Xname and the directory name yourself. If you use the PathName Xvariable then it is quite reasonable to leave the File field blank, Xsince all the information you need can be obtained from the PathName Xstring. X X The FRQINFOGADGETM flag specifies whether or not a hide/show info Xgadget should appear on the file requester. This lets the user toggle Xthe state of the FRQSHOWINFOM flag to decide whether or not to let X'*.info' files show up. This is not recommended for most programs, Xsince most users have no reason to look at '*.info' files. The Xdefault is to _not_ have this gadget show up. X X The FRQHIDEWILDSM flag specifies whether or not to have 'show' and X'hide' string gadgets. These gadgets let the user use wildcards to Xspecify which files should show up. All files are first compared Xagainst the 'show' gadget. If they fail the comparison, they are not Xdisplayed. Then they are compared against the 'hide' gadget. If they Xmatch here then they are not displayed. If the gadgets are empty, no Xcomparisons are done. Important note: Even if these gadgets are not Xdisplayed, the comparisons are still done on the data which is in the XHide and Show fields of the file requester structure. The standard XAmigaDOS wildcards (including '#', '?', '|' and '*') are supported. X X Normally the file requester appears centered under the mouse Xpointer. If you would like to specify its opening position you must Xset the ABSOLUTEXYM flag and then put the x,y position in XWindowLeftEdge and WindowTopEdge. X X If you feel that the file requester's cached directories (selected Xby FRQCACHINGM) should be purged whenever the directory has been Xchanged, then set FRQCACHEPURGEM field and the file requester will Xcheck the dates whenever it is opened. X X If you feel that the file requester should never cache directories Xunless it manages to read in the entire directory before the user Xsends it away, then set the FRQNOHALFCACHEM flag. This flag will Xcause the file requester to automatically flush any incompletely read Xdirectories when it exits. X X If you would like your directories to appear in 'natural' order Xinstead of alphabetically sorted, set the FRQNOSORTM flag. X X If you would like the file requester to appear without a drag bar Xor depth arrangement gadgets, set the FRQNODRAGM flag. X X If you are using the file requester to select a filename to save Xto, you should set the FRQSAVINGM flag. Similarly, if you are using Xthe file requester to select a filename to load from, you should set Xthe FRQLOADINGM flag. These flags are not currently used by the file Xrequester, but they may be used in the future. They also make it Xeasier for people who want to personalize the file requester to make Xit behave differently for loading vs. saving. X X X The various color fields let you specify the colors of many Xaspects of the file requester. If they are left as zero then the file Xrequester uses various non-zero certain default values for them. X X The WindowLeftEdge and WindowTopEdge fields are covered in the Xsection on the ABSOLUTEXYM flag. X X The FontYSize and FontStyle fields are covered in the section on Xthe FRQGETFONTSM flag. X X The ExtendedSelect field is covered in the section on the XFRQEXTSELECTM flag. X X The Hide and Show fields are covered in the section on the XFRQHIDEWILDSM flag. X XSet this bit if you are selecting a file to save to. XSet this bit if you are selecting a file(s) to load from. XThese two bits (save and load) aren't currently used for Xanything, but they may be in the future, so you should Xremember to set them. Also, these bits make it easier if Xsomebody wants to customize the file requester for their Xmachine. They can make it behave differently for loading Xvs saving. X X The four BufferPos and DispPos variables are copies of the Xequivalent variables from the four string gadgets. This is so that Xwhen the file requester goes away and then is brought up again, the Xcursor in the string gadgets will appear in the same places as before. XThese fields should not need to be touched by the programmer. X X The rest of the fields are private. Don't go touching them. We Xguarantee to move them around and change their meaning, just to make Xsure that nobody tries to use them. They are largely concerned with Xkeeping track of memory used in directory caching. This memory is Xfreed with the PurgeFiles() routine. That's all you should need to Xknow. X X X X X X;-------------------------------------------------------------------- X XRealTimeScroll X XNAME X RealTimeScroll - do the calculations necessary for a responsive, Xpixel resolution, real time scroll routine. X XSYNOPSIS X RealTimeScroll(&ScrollStruct); X A0 X XFUNCTION X Make the implementation of real time scrolling area easier and Xmake the real time scrolling area more responsive to the user by doing Xpixel resolution scrolling and by checking the current position of the Xscroll bar in mid scroll. This routine calculates how far to scroll Xeach time and calculates which lines of text, graphics etc. need to Xbe redrawn to fill in the empty area. X XINPUTS X &ScrollStruct - pointer to an initialized scroll structure. X XRESULT X This routine returns no result code. X XBUGS X None known X XSEE ALSO X n/a X X X It is relatively easy to implement a real time scrolling area, but Xthe most obvious implementations suffer from a lack of responsiveness. XTypically the routines look at where the scroll bar is, calculate Xwhere to scroll to, scroll there in several jumps to make the Xscrolling look smooth, and the examine the scroll bar again to see if Xit has moved. This means that there are periods, perhaps annoyingly Xlong, where the program may be scrolling in one direction while the Xscroll bar is being dragged in another. The answer is to examine the Xscroll bar to find out the desired location, scroll partway towards Xthe destination and then recheck the scroll bar's location. This can Xgreatly increase the responsiveness, since the program is checking Xafter every ScrollRaster() call, instead of after a dozen or more. XHowever, the calculations, especially of which lines need to be Xrefreshed and where, get somewhat more complicated. This routine is Xdesigned to simplify this situation by taking care of as many of the Xmessy details as possible. X X First you must initialize the scroll structure. The XTopEntryNumber, NumEntries and NumLines fields describe where the data Xis currently. NumEntries is the number of lines of data in total, XNumLines is the number of lines that are visible, and TopEntryNumber Xis the line number of the first line visible (it therefore ranges from Xzero to NumEntries - 1). X X LineSpacing is the number of pixels high that each line of data Xis. For text this will typically be eight or nine (for eighty or Xsixty column topaz). This can be set to one if your data is Xcontinuous (as in the case of some graphics). X X PropGadget is a pointer to the prop gadget which is being used to Xcontrol this scroll area. X X RedrawAll is a pointer to a function that you must supply to Xredraw the entire visible window. This routine is called whenever the Xuser gets so far ahead of the scroll routine that scrolling to where Xthe users wants to be would take to long. Before calling this Xroutine, the ScrollStruct that was passed to this routine is updated Xwith the desired TopEntryNumber so that your routine will know which Xdata to redraw. X X ReadMore is an optional routine that will usually not be used. It Xis used if more data is being added while the scrolling is going on. XThis is used, for instance, by the FileRequest in the requester Xlibrary, to continue attempting to read the directoy while the user is Xscrolling. Leave this set to zero if you don't need it. It is only Xcalled when no scrolling is being done, but the user has not released Xthe scroll bar. X X ScrollAndDraw is the most important routine. This routine, which Xyou must supply, is called whenever the data must be scrolled. The Xactual scrolling and redrawing of the data is done by this routine, Xbut because the scroll amount, the lines to be drawn and the number of Xlines to be drawn are passed to this routine, the routine is fairly Xsimple. Four parameters are passed to this routine: X XScrollAndDraw(firstlinenum, firstliney, scrollamount, numlines); X X All four parameters are passed as longs, both on the stack and in XD0-D3, so that the routine can easily be written in either C or Xassembler. X X When the ScrollAndDraw, ReadMore or RedrawAll routines are called, XA4, A5 and A6 all contain the same values they contained when XRealTimeScroll was called. This allows programs written in C using Xthe small data model to be able to access their data properly from Xthese routines without any special work. All other registers (except Xthose that are used to pass parameters in) could contain anything. X X X X X;-------------------------------------------------------------------- X X X XTextRequest X XNAME X TextRequest - bring up a text requester with one to three gadgets Xand get a response. X XSYNOPSIS X result = TextRequest(&TRStructure); X D0 A0 X XFUNCTION X Bring up a requester (actually a window) containing a message to Xthe user and give him a choice of from one to three different Xresponses. The window automatically sizes to fit the text and Xprintf() style formatting can be used by TextRequest() to generate the Xmessage to the user. X XINPUTS X &TRStructure - pointer to an initialized text requester structure. X XRESULT X Returns either zero, one or two, depending on which gadget the Xuser clicks on. All of the gadgets are optional, so that the Xrequester can be used to bring up requesters that give the user a Xmessage, without demanding an answer, by having only a single gadget. XThe gadget in the lower right hand corner (the negative gadget) Xreturns a zero, the gadget in the lower left hand corner (the positive Xgadget) returns a one and the gadget in the middle returns a two. If Xnone of these three gadgets are requested, a close gadget is attached Xto the window and it returns a zero. X XBUGS X If any line of the text to be printed is too long, then the Xrequester will attempt to open up an impossibly large window, which Xwill fail and the requester will return a zero. X The buffer used for formatting the text is 5000 bytes long, so no Xmessages can be longer than this. X XSEE ALSO X SimpleRequest X TwoGadRequest X X X The purpose of this routine is to make it as easy to print Xformatted messages in intuitionized window with gadgets as it is to Xprint them on the CLI screen. For maximum ease of use, at a loss of Xflexibility, please see the functions SimpleRequest and TwoGadRequest Xwhich are simply glue code functions to make calling TextRequest a Xtrivial matter. X X If you want the text requester to appear on a custom screen, then Xyou must set the pr_WindowPtr field in your process structure to point Xat one of the windows on your screen (this should be done anyway, so Xthat DOS requesters appear on your custom screen). This field is Xlooked at by all functions in the requester library so this way is the Xsimplest method. Important note: It is VERY important that you reset Xthe pr_WindowPtr field back to its original value before your program Xexits. If you don't, the next program run may try to open a requester Xwindow on a now closed screen. X X The structure whose address is passed to this routine must be Xinitialized first. X X The Text field is initialized with the body of the text you would Xlike displayed. This text can contain both printf() style formatting Xand end of line characters ('\n' in C, ascii 10 in assembler). The Xprintf() style formatting, is expanded out into the final text string Xusing the parameter list which is pointed to by the Controls field. XLine feeds are used, as usual, to specify a new line, thus allowing Xvery long and complex messages to be displayed. The are some Xlimitations on the types of printf() formatting that can be used. XSince the RawDoFmt() function of the ROM is used to do the formatting, Xonly functions supported by it can be used. For complete Xdocumentation, see the documentation of the RawDoFmt() command. The Xmain things to be aware of is that floating point numbers can not be Xprinted, and, if you are using a compiler that uses thirty-two bit Xints then we will have to specify '%ld' to print an int, since the XRawDoFmt command assumes an int size of sixteen bits. X X The Controls field points to a list of parameters, one for each of Xthe '%' parameters in the Text field. Normally these will be pushed Xon to the stack and the stack pointer copied into the Controls field. XThe first parameter used (the first one to occur in the string) should Xbe at the beginning of the list, that is, at the lowest address, the Xone pointed at by the Controls parameter. X X The Window field can be used to specify what screen you would like Xthe requester to appear on. This field is usually not necessary since Xthe same information can be conveyed in the pr_WindowPtr field of your Xprocess structure. However this field was left in so that the XTextRequest function could be called from a task (which lacks a Xprocess structure and therefore a pr_WindowPtr field). If this field Xis non-zero or if the calling program is a task then this field takes Xprecedence over the pr_WindowPtr field. X X MiddleText, PositiveText and NegativeText are the pieces of text Xused for the three gadgets. These three gadgets, when present, are Xplaced in the middle, the left and the right of the window Xrespectively. All three gadgets are placed along the bottom of the Xwindow. All of the gadgets are optional. If a gadget is not wanted, Xthe text pointer should be set to zero. The values returned if the Xuser clicks on these gadgets are two, one or zero, respectively. If Xnone of the gadgets are present (if all of the text fields are zero) Xthen a standard CLOSEWINDOW gadget is attached to the window. This Xgadget returns a zero. X X The requester attempt to appear so that the negative gadget is Xunderneath the mouse pointer. If the negative gadget is not present Xit will attempt to appear so that a different gadget is underneath the Xmouse pointer. This is to make it as convenient as possible for the Xuser to respond to, and especially to respond negatively to, the Xrequester. X X In addition to responding to the requester with the mouse, Xkeyboard shortcuts are available. The user can type ESC, 'N', 'Q' or X'B' as a shortcut to clicking on the negative gadget. The user can Xtype 'Y' or 'V' as a shortcut to clicking on the positive gadget and Xcan type 'M' as a shortcut to clicking on the middle gadget. X X The Title field of the structure should either point to a null Xterminated string to be used in the windows title bar or should be Xnull. X X The KeyMask field is used to regulate the use of keyboard Xshortcuts. The qualifier field of all keyboard messages is ANDed with Xthis field, and the keypress is ignored if the result is zero. XTherefore, to enable all keypresses to be used as keyboard shortcuts, Xinitialize this field to $FFFF. To turn off the keyboard shortcuts, Xinitialize this field to 0. To force the user to hold down the left Xor right amiga key, initialize this field to AMIGAKEYS. X X The textcolor, detailcolor and blockcolor fields can be left Xunitialized (ie; set to zero) if you wish, in which case the requester Xwill use the default values of one, zero and one respectively. The Xtextcolor field is used for the color of the actual text message and Xthe detail and block color fields are simple copied into the fields of Xthe same name in the new window structure. X X;-------------------------------------------------------------------- X X XSimpleRequest X XNAME X SimpleRequest - bring up a text requester and wait for the user to Xacknowledge it. X XSYNPOSIS X SimpleRequest(string, parameterlist, , ,) X A0 A1 X XFUNCTION X Bring up a requester (actually a window) containing a message to Xthe user and wait for the user to acknowledge it. The window Xautomatically sizes to fit the text and printf() style formatting can Xbe used by TextRequest() to generate the message to the user. X XINPUTS X string - a null terminated string, containing printf() style Xformatting commands if desired. X parameterlist - the parameters corresponding to the printf() style Xformatting commands in the string. In C these are listed after the Xcontrol string, exactly as with printf(). In assembler, the address Xof the list of parameters is put in A1. X XRESULT X No result code is returned. X XBUGS X See TextRequest X XSEE ALSO X TextRequest X TwoGadRequest X X X This function was designed to make it as easy to give messages to Xthe user and await acknowledgment in an intuition style requester as Xit is using printf() and getc(). Simply replace almost any call to Xprintf() with a call to SimpleRequest and a requester will appear and Xnot disappear until the user acknowledges it (either with a keystroke Xor with the mouse). X X Example: X SimpleRequest("There have %d changes made to this file.", X numchanges); X X Please see the TextRequest documentation for further important Xdetails. This routine is simply a few lines of assembler glue code Xfor the TextRequest routine. The TextRequest routine is a little bit Xmore complicated to use, but it allows correspondingly more Xflexibility. It is fairly simple to modify the glue code to allow Xstill more high level entry points to the TextRequest routine. X X X This is a complete program that makes use of the SimpleRequest Xfunction from assembler, and demonstrates a few of the features of XFormat (which is used by SimpleRequest). X X;-------------------------------------------------------------------- X;-----CUT HERE---------------CUT HERE-------------------------------- X;-------------------------------------------------------------------- X X INCLUDE "libraries/reqbase.i" X X public SimpleRequest X public _ReqBase,_main X X;-------------------------------------------------------- X; This file should be linked with reqglue.o, for the SimpleRequest X;function. X;-------------------------------------------------------- X XSYS MACRO X XREF _LVO\1 X JSR _LVO\1(A6) X ENDM X X;-------------------------------------------------------- X X X_main X OpenReq Xmystart X X MOVE.L A6,A5 X MOVE.L A6,_ReqBase X X X PEA string X MOVE.L #$C0FFEE,-(SP) X MOVE.W #$1CE,-(SP) X MOVE.W #'B',-(SP) X MOVE.L #-12345,-(SP) X MOVE.L SP,A1 X LEA Text,A0 X JSR SimpleRequest X X LEA 16(SP),SP X X MOVE.L A5,A1 X MOVE.L 4,A6 X SYS CloseLibrary X X MOVEQ #0,D0 X RTS Xstring X DC.B "This is a string.",0 XText X DC.B "A long (signed) decimal is: %ld,",10 X DC.B "a character is: %c,",10 X DC.B "a 16 bit hex val might be: %x, ",10 X DC.B "a register-style format 32 bit hex: $%08lx,",10 X DC.B "and a string might read: `%s'.",0 X X dseg X X_ReqBase DC.L 0 ;The SimpleRequest function in the glue code X ;needs this variable. X X END X X;-------------------------------------------------------------------- X;-----CUT HERE---------------CUT HERE-------------------------------- X;-------------------------------------------------------------------- X X X X X;-------------------------------------------------------------------- X X X XTwoGadRequest X XNAME X TwoGadRequest - bring up a text requester and wait for the user to Xacknowledge it. X XSYNPOSIS X result = TwoGadRequest(string, parameterlist, , ,) X A0 A1 X XFUNCTION X Bring up a requester (actually a window) containing a message to Xthe user and wait for the user to click on either the OK or the CANCEL Xgadget. The window automatically sizes to fit the text and printf() Xstyle formatting can be used by TextRequest() to generate the message Xto the user. X XINPUTS X string - a null terminated string, containing printf() style Xformatting commands if desired. X parameterlist - the parameters corresponding to the printf() style Xformatting commands in the string. In C these are listed after the Xcontrol string, exactly as with printf(). In assembler, the address Xof the list of parameters is put in A1. X XRESULT X Either one or zero is returned, depending on whether the user Xselected, respectively, the OK or the CANCEL gadget. X XBUGS X See TextRequest X XSEE ALSO X TextRequest X SimpleRequest X X X This function was designed to make it as easy to give messages to Xthe user and get a response in an intuition style requester as it is Xusing printf() and getc(). Simply replace almost any call to printf() Xwith a call to SimpleRequest and a requester will appear and not Xdisappear until the user responds to it (either with a keystroke or Xwith the mouse). X X Example: X if (TwoGadRequest("There have %d changes made to this file.\n" X "O.K. to continue?", X numchanges)) X exit(10); X X Please see the TextRequest documentation for further important Xdetails. This routine is simply a few lines of assembler glue code Xfor the TextRequest routine. The TextRequest routine is a little bit Xmore complicated to use, but it allows correspondingly more Xflexibility. It is fairly simple to modify the glue code to allow Xstill more high level entry points to the TextRequest routine. X X X X------------------------------------------------------------------- XNAME X GetString X XBOOL = GetString(buffer, title, window, visiblechars, maxchars) XD0 A0 A1 A2 D0 D1 X XDESCRIPTION X This routine allows you to bring up a nice intuition style string Xrequester in its own window and get a single line of input from the Xuser in just a one line function call. X X buffer points to the a buffer containing the string which will Xappear when the string gadget first appears and it is also where the Xresult will be put, if this routine returns TRUE. X Title is a pointer to a null terminated string that will be used Xfor the window title. X Window can be used to specify what screen you would like the Xrequester to appear on. You simply put a window pointer in it (or a Xzero if you want the requester to appear on the workbench screen). If Xyou have already set your pr_WindowPtr then you can simply pass a zero Xfor the window pointer and the pr_WindowPtr value will be used. X visiblechars specifies how many characters should actually be Xvisible at one time. X maxchars specifies how long the buffer is, including the Xterminating zero. X XRETURNS X This routine returns true or false, depending on whether the user Xclicked on the cancel gadget (FALSE) or clicked on the OK gadget X(TRUE) or clicked on the close window gadget (FALSE) or hit return in Xthe string gadget (TRUE). X XBUGS X None known. X X X X------------------------------------------------------------------- XNAME X GetLong X XBOOL = GetLong(&GetLongStruct) XD0 A0 X XDESCRIPTION X This routine allows you to bring up a nice intuition style string Xrequester in its own window and get a single signed thirty-two bit Xnumber from the user in just a one line function call (although a few Xfields in the structure must be initialized first). X X The GetLongStruct contains fields for letting you specify the Xtitle bar message, the default value that should appear in the Xrequester and the maximum and minimum values that the routine should Xallow to be entered. If the routine returns TRUE (indicating Xsuccessful entry of a number) then the result is returned in the Xresult field of the structure. X The window field can be used to specify what screen you would like Xthe requester to appear on. You simply put a window pointer in it (or Xa zero if you want the requester to appear on the workbench screen). XIf you have already set your pr_WindowPtr then you can simply leave Xthe window field zeor and the pr_WindowPtr value will be used. X XRETURNS X This routine returns TRUE or FALSE (1 or 0) in D0 to specify Xwhether or not the user successfully entered a number. If this Xroutine returns TRUE then you can find the result in the result field Xof the GetLongStruct whose address you passed to GetLong. X X X X------------------------------------------------------------------- XRawKeyToAscii X XSYNOPSIS X X key = RawKeyToAscii(Code,Qualifier,IAddress) X D0 D0 D1 A0 X X UWORD Code,Qualifier; X APTR IAddress; X XFUNCTION X X Have you ever wanted to have both RAW and COOKED keys? You can do Xit by checking the keys for whatever raw keys you want, and then using Xthe console.device's RawKeyConvert routine, except that it's a hassle Xto start mucking about with the device. X X Well, here you go! A nice, clean way of converting from a raw key Xto a cooked key, in a single call! All you have to do is pass the Xcode and qualifier from your intuimessage, and the address of the Xmessage itself, and you will get back the ASCII value of the key that Xwas hit. This does, in fact, use the console.device's RawKeyConvert, Xso that if you have a different keymap set, it will be used. X XEXAMPLE X X Xstruct IntuiMessage *im; X X key = RawKeyToAscii(im->Code,im->Qualifier,im->IAddress); X END_OF_FILE if test 60498 -ne `wc -c <'req.doc'`; then echo shar: \"'req.doc'\" unpacked with wrong size! fi # end of 'req.doc' fi echo shar: End of archive 3 $of 3$. cp /dev/null ark3isdone MISSING="" for I in 1 2 3 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 3 archives. rm -f ark[1-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0 -- Mail submissions (sources or binaries) to <amiga@uunet.uu.net>. Mail comments to the moderator at <amiga-request@uunet.uu.net>. Post requests for sources, and general discussion to comp.sys.amiga.